LESSON 7
CUSTOM EXPAND PATTERN
VERSION 7.1

This lesson introduces the magic expand function, which allows a two color graphic pattern to be stored in one half the normal memory. For example, the Gunfight's graphic tree pattern seen on the TV screen is 2 bytes wide by 17 bytes high requiring a total of 34 bytes to be written (displayed) on the screen. This 2 color pattern, when utilizing the magic expand function, can be stored in memory using only 17 bytes, where in this case, each byte defines one horizontal pattern line of 2 bytes. The magic expander will take each bit in a pattern byte stored in memory and expand it into the pixel colors defined by the Expand Register bits 3 to 0 (output port 19H). Both the magic expand function and the Expand Register are described in the Nutting Manual system description, page 95. Bits 1 and 0 in the Expand Register define the pixel color for an unexpanded pattern bit=0 stored in memory. Bits 3 and 2 in the Expand Register define the pixel color for a pattern bit=1 stored in memory. There are only 4 possible pixel colors 00,01,10 or 11 that a pattern bit can be expanded into. The actual pixel color is mapped according to the color registers 0 thru 7 (see the previous LESSONS 1 and 2). A graphic ML subroutine must be provided and executed to support the magic expand function when writing graphic patterns to screen RAM. One of the 3 magic functions XOR,OR,plop can be combined with the magic expand function. The magic shifting of 1,2 or 3 pixels to the right can also be implemented. Note that the following LESSON 8 will introduce the flop and expanded write.

EXAMPLE 7-1

Program Description

This example will write with expand one line of 2 bytes from just a single pattern byte. A single shifter byte will also be written at the end of this 2 byte expanded write so that the magic shifter can also be experimented with. The write with expand will occur 2 lines below a green reference byte located at the screen address 4014H, just like the magic writes in the previous lesson  example programs. The reference byte will be written near the middle of the screen RAM area on the very first (top) line. The single pattern byte to be expanded, will be stored just below the program which begins at 4E10H.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Example Program 7-1

	WRITE REFERENCE BYTE
4E10H	CD 47 23		CALL Clear		use MLM Clear screen sub.
4E13H	3E FF			LD A,FFH		A = color value = 11 11 11 11							   		  = solid green
	32 14 40		LD (4014H),A	write the green reference byte
							to screen RAM.
	SET UP MAGIC REGISTER
4E18H	3E 08			LD A,MREG		A = magic register value
							  = 0000 1000 = 08H
							expand with a plop write and no
							pixel shifting to the right.
	D3 0C			OUT (MAGIC),A	output the magic function request.
							bits 1-0 shift 0,1,2 or 3 pixels
						        "  3   expand write
							  "  4   OR write
							  "  5   XOR write
							plop write when bits 4=5=0.
							See NM system description, page 94.
							Output also resets to 0 hardware 								expand flip-flop.

	SET UP EXPAND REGISTER
4E1CH	3E 08			LD A,0000 1000	bits 1,0 expand a zero(0) bit in
							pattern byte to color 00 (blk).
							bits 3,2 expand a one(1) bit in
							pattern byte to color 10 (red).
	D3 19			OUT (XPAND),A	output expand request to expand
							register.
							See Note 1.

	WRITE WITH EXPAND PATTERN BYTE
4E20H	11 2E 4E		LD DE,4E2EH		DE = points to pattern byte address.
	1A			LD A,(DE)		put pattern byte in A.
	21 64 00		LD HL,0064H		point HL at magic address to write to
							write 2 lines below the reference 								byte. See note 2.
	77			LD (HL),A		write with expand bits 4 to 7 in the
							pattern byte.
							expand flip-flop = 0 prior to the
							write. See note 1.

	23			INC HL		point HL at the next magic address.
4E29H	77			LD (HL),A		write with expand bits 0 to 3 in
							pattern byte.											expand flip-flop=1 prior to the write

	WRITE FINAL SHIFTER BYTE IN THIS LINE
4E2AH	23 			INC HL		point HL at final magic address to
							write to.
	AF			XOR A 		A = 0 = shifter clear byte.
	77			LD (HL),A		write the final shifter byte.
							clear the final shifter byte in this
							line.
							write with expand bits 4 to 7 in the
							shifter byte.
							in this case, bits 4-7 are all zero.
							So, the shift byte is expanded and
							written with all zeros (background
							color 00 = black).
							expand flip-flop = 0 prior to the
							write.
						      See note 3.
4E2DH	C9			RET			return to MLM

	PATTERN BYTE
	THIS BYTE WILL BE EXPANDED INTO 2 BYTES
4E2EH	AD	1010 1101  See note 4.

NOTES

1. Reference NM system description, page 95.
2. Reference EXAMPLE 4-1 (in LESSON 4).
3. Only one shifter byte is used in this example since only ONE pattern line is   written. Normally, 2 shifter bytes are written at the end of every pattern line, so that the hardware expand flip-flop will be reset to zero for the next line to be written.
4. The single pattern byte is expanded into 2 bytes as indicated below.
   10  00  10  00  10  10  00  10
   red blk red blk red red blk red

   GGGG		G=green pixel (in the reference byte)

   RBRBRRBR       R=red pixel,B=black pixel (in the expanded pattern bytes  				below the green reference byte)

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Beginner Exercises

1. Change the Expand Register set up as indicated below.

4E1CH	3E 0C			LD A,0000 1100	  11=green, 00=black

How will this change affect the expanded write?

0CH = 0000 1100

All pattern bits at logic one (1) will now be expanded to the pixel color 11, which is green. Change the program byte at 4E1DH to 0CH and execute the program to confirm the expected change.

The expanded pattern byte will be written as indicated below.

11  00  11  00  11  11  00  11
grn blk grn blk grn grn blk grn

2. Change the Expand Register set up again as indicated below.

4E1CH	3E 09			LD A,0000 1001	  10=red, 01=white

Can you predict how the expanded pattern byte will appear on the screen?
The MLM pixel colors are listed below.

MLM colors
11 green
10 red
01 white
00 black

Execute the program with this change. Now all the expanded pattern bit 1 pixels will be red with the expanded pattern bit 0 background pixels white. Note that you can now see the final shifter byte with white pixels.

GGGG			G = green reference byte

RWRWRRWRWWWW	R = red, W = white, pattern byte expanded into 2 bytes
			ending with a single shifter byte

3. You can also shift right the expanded pixels in Experiment 2. Shift the pixels right by changing the Magic Register set up as indicated below. You are now changing the program at 4E18H to shift the pixels right. Do not change the
program at 4E1CH, so you can observe the pixel shift. 

A. Shift the expansion right 1 pixel. Note the first pixel in the expanded write is set to color 00 (blk). With a magic shift right, the first pixel is
reset to 00 by the magic hardware. See the NM system description illustration on page 97.

4E18H	3E 09			LD A,0000 1001	 	 A = 0000 1001
								 expand write with a plop and 								 shift right 1 pixel.
GGGG

BRWRWRRWRWWW

B. Shift the expansion right 2 pixels.

4E18H 3E 0A			LD A,0000 1010		A = 0000 1010
								expand write with a plop and 									shift right 2 pixels.
GGGG

BBRWRWRRWRWW

C. Shift the expansion right 3 pixels.

4E18H	3E 0B			LD A,0000 1011		A = 0000 1011
								expand write with a plop and
								shift right 3 pixels.
GGGG

BBBRWRWRRWRW

EXAMPLE 7-2

Program Description

The program below utilizes the onboard ROM subroutine MWX (macro write expanded) to write with expand a graphic pattern xsize bytes wide by ysize lines high. This subroutine is a portion of the onboard Sub#38, MWRITA (macro write absolute) and is listed in the NM, onboard ROM (Z80) code listing, page 50. Sub#38 is stacked below Sub#30 thru Sub#36. Sub#38 contains all the graphic pattern write subroutines. As shown below, the subroutine can be used to write a two color graphic pattern to magic RAM using the magic expand function. In this case, the unexpanded pattern is a Gunfight tree. This pattern is stored at 4E3BH following the program at 4E10H. Subroutine MWX will also allow the magic functions XOR,OR,shifter to be implemented simply by changing the Magic Register byte value which is output to the Magic Register port 08H.

This program writes with expand, the green Gunfight tree, in the top center of the screen.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Example Program 7-2

	4E10H	CD 47 23	CALL Clear		use MLM Clear screen sub.

	      SET UP MAGIC REGISTER
	4E13H	3E 08		LD A,MREG		A = Magic Reg value = 0000 1000
							expand with a plop write and no
							pixel shifting.
		D3 0C		OUT (MAGIC),A	output the magic byte value.
							reset expand flip-flop to zero.

	      SET UP EXPAND REGISTER
	4E17H	3E 0C		LD A,0000 1100	expand with a green pixel 11 on
							a black pixel 00 background.
		D3 19		OUT (XPAND),A	output the expand byte value.

		WRITE WITH EXPAND USING A COPY OF ROM ROUTINE MWX
		Enter MWX with:
		Magic Register and Expand Register set up.
		DE = magic address to begin the magic write with expand
		HL = "pattern to expand" address
		 C = pattern xsize (# of bytes wide)
		 B = pattern ysize (# of lines high)

	4E1BH	11 14 00	LD DE,0014H		DE = magic address
							begin write for screen address 4014H,
							the screen address at top line,
							middle of screen. However, use
							magic address 0014H for the write.
	4E1EH	21 3B 4E	LD HL,PADR		point HL at pattern address.
	4E21H	01 01 11	LD BC,1101H		C = xsize = 01H byte wide.
							B = ysize = 11H (17) lines high.
MWX	4E24H	EB		EX DE,HL		DE = pattern address
							HL = magic address
MWX1		C5		PUSH BC		save ysize,xsize
		E5		PUSH HL		save magic address
		41		LD B,C		B = xsize counter
MWX2		1A		LD A,(DE)		put pattern byte in A
		13		INC DE		point DE at next pattern byte
		77 		LD (HL),A		write with expand bits 4 to 7 in
							pattern byte.
							expand flip-flop = 1 after this
							write is executed.
		23		INC HL		point HL at next magic address.
	4E2CH	77		LD (HL),A		write with expand bits 0 to 3 in
							pattern byte.
							expand flip-flop is reset to zero
							after this write is executed.
		23		INC HL		point HL at next magic address
		10 F8		DJNZ MWX2		loop back to finish writing the line?
							B = xsize counter not 0, loop back.
							B = xsize = 0, continue. The line is  							written.
	4E30H	70		LD (HL),B		B = 0 from DJNZ instruction.
							write expanded shifter byte at the 								end of line (bits 4 to 7 in B are 								expanded to pixel 00).
							clear (zero) the shifter byte.
		23		INC HL		point HL at next magic address
		70		LD (HL),B		write 2nd expanded shifter byte
							(bits 0 to 3 in B are expanded to 								pixel 00).
							clear (zero) also this shifter byte.
						      This write resets the expand flip-								flop to zero for the next line to be 							written.
		E1		POP HL		put saved initial magic address of
							line just written in HL.
		0E 28		LD C,BYTE		C = # of bytes in one screen line.
							  = 40 = 28H.
							B = still zero.
		09		ADD HL,BC		point HL at initial magic address of
							next line.
		C1		POP BC		put saved ysize,xsize back in BC
							for loop back (restore the stack).
		10 EB		DJNZ MWX1		loop back to write next line.
							if final line was written, then 								exit this subroutine.
	4E3AH	C9		RET			return to MLM.

      NONEXPANDED GUNFIGHT TREE PATTERN
      (2 colors, CLR1 is the tree, CLR0 is the background color)
PADR	4E3BH	08 	00001000
		1C	00011100
		3E	00111110
		6B	01101011
		08	00001000
	4E40H	08	00001000
		3C	00111100
		7E	01111110
		A9	10101001
		08	00001000
		3C	00111100
		7E	01111110
		EB	11101011
		89	10001001
		08	00001000
		1C	00011100
	4E4BH	AE	10101110

NOTES
MLM colors are:
COL3 = green = 11
COL2 = red   = 10
COL1 = white = 01
COL0 = black = 00

After you entered this program using MLM, call 4E10H to execute and write the tree.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Beginner Exercises

Reference the NM system description pages 82-86, 94–97 and 100 for info related to these exercises.

1. You can change the color of the tree to white (color 01) or red (color 10) by changing the bits 3 and 2 in the Expand Register set up at 4E17H.

4E17H	3E 04		LD A,0000 0100		white tree in black background
     or
4E17H	3E 08		LD A,0000 1000		red tree in black background

You can also change the background color to white, red or green by changing the bits 1 and 0 in the Expand Register set up to 01, 10 or 11 respectively.

4E17H	3E 0D		LD A,00001101		green tree in white background
     or
4E17H	3E 0E		LD A,00001110		green tree in red background
     or
4E17H	3E 0B		LD A,00001011		red tree in green background
		
2. You can relocate the tree, for example, at the top left corner by writing the tree to the magic address 0000H or at the top right corner by writing to magic address 0024H.

4E1BH	11 00 00	LD DE,0000H 		write tree at 4000H, top left corner							by writing to magic address 0000H.
     or
4E1BH	11 24 00	LD DE,0024H			write tree at 4024H, top right corner
							by writing to magic address 0024H.

Note
If you write the tree at magic address 0025H or 0026H, there will be a wrap around on the left side of the screen, but 1 line lower. This is normal because of the way magic RAM (screen RAM) addresses are mapped out.

3. You can also shift the tree right 1,2 or 3 pixels by changing the bits 1 and 0 in the Magic Register set up to 01,10 or 11 respectively. You can see the shift by changing the expand background color to a color other than black.

Change one instruction in the program as indicated below, then call the program at 4E10H.

4E17H	3E 0D		LD A,0000 1101		green tree in white background

The green tree is now written with a white (color 01) background. When you examine the above program, the tree pattern at 4E3BH is expanded into 2 bytes of 8 pixels. You can visually see the tree is 8 pixels wide. There are also 2 shifter clear bytes written at the end of each pattern line. So, the pattern frame, which is visible in white, is a total of 4 bytes wide. Note that the tree is up against the left side of the white pattern frame. This is the position of the tree within the written 4 byte wide x 17 line high pattern frame when the tree is NOT shifted right 1,2 or 3 pixels.

Now change the program as listed below.

4E13H	3E 09		LD A,MREG			A = Magic Register value
							  = 0000 1001 = 09H
        					      expand, plop and shift right 1 pixel

Just change the byte at 4E14H to 09. You should have room to enter 4E13H to call the program at that address without erasing the written tree already on the screen. Calling the program at 4E13H will not clear the screen and will plop write a shifted tree over the tree that is on the screen now. When you call the program this way, you will see the tree shift 1 pixel to the right. Note that there is a 1 pixel black indentation in the upper left corner of the white pattern frame. The reason this black indentation is present is explained in note B below.

You can also shift the tree 2 or 3 pixels to the right as indicated below. Make the change and call the program at 4E10H to see the shift. Note that the black indentation will increase in length 2 or 3 pixels when you shift right 2 or 3 pixels respectively.

4E13H	3E 0A		LD A,MREG			A = 0000 1010 = 0AH
    							expand, plop and shift right 2 pixels
     or
4E13H	3E 0B		LD A,MREG	 		A = 0000 1011 = 0BH
							expand, plop and shift right 3 pixels

Notes
A. If you change the program and expand with a shift right at magic address 0026H (screen address 4026H), there will be a shift right wrap around on the left side of the screen, but at 1 line lower.

B. Normally, the 1,2 or 3 pixels to the LEFT of a pixel shift right are always set to the color 00. See the NM system description illustration on page 97. In this case color 00 is black. This will always be the case when the expanded background color (bits 1,0) in the Expand Register is set to color 00. However, this may not be the case when the expanded background color is set to a color other than color 00 and when more than one horizontal line is expanded and shifted. You may find that ONLY in the first expanded line, will the initial 1,2 or 3 pixels be reset to the color 00. This decrepancy may be inherant in the magic hardware.

4. You can also write using the magic XOR, magic OR function instead of a magic plop by setting the Magic Register bit 5 or bit 4 respectively. However, in this program, you can't visibly observe the XOR,OR,plop writes, unless you use the MLM list command to list MLM text (graphics) at the top of the screen and then call the program at 4E13H instead of 4E10H, so the screen is not cleared. Also, use (restore) the program as listed above writing a green tree with a black background, so it is easier to see the magic OR,XOR logical writes. Then, write with a magic OR, magic XOR with the change indicated below.

4E13H	3E 18		LD A,MREG		A = Magic Register value
						  = 00001 1000 = 18H
     or					expand with an OR write and no
						pixel shift right
4E13H	3E 28		LD A,MREG		A = Magic Register value
						  = 0010 1000 = 28H
						expand with a XOR write and no
						pixel shift right

The magic XOR,OR functions operate logically on the screen RAM pixel bits present at the time of the magic write. See NM system description, page 100 for some info on the magic XOR,OR functions (logical operations). Reference also Lesson 4, An Introduction To The Magic RAM, for introductions to the magic XOR,OR logical operations.

EXAMPLE 7-3

You can also use the subroutine MWX to write expanded custom text.

Restore the Example Program 7-2 as originally listed, then make the following changes to the program to display the text following the program at 4E3BH.

4E21H	01 06 05	LD BC,0506H		C = xsize = 6 bytes wide
						B = ysize = 5 lines high

4E3BH 8A 27 3E BE 08 BE
	8A 28 88 A0 08 A2
4E47H	AB EF 88 3E 08 BE
	DA 28 88 02 08 A0
4E53H	8A 28 88 3E 0F A0

The pattern breakdown is shown below.
1 = char color, 0 = background color

10001010  00100111  00111110  10111110  00001000  10111110
10001010  00101000  10001000  10100000  00001000  10100010
10101011  11101111  10001000  00111110  00001000  10111110
11011010  00101000  10001000  00000010  00001000  10100000
10001010  00101000  10001000  00111110  00001111  10100000

   8A        27        3E        BE        08        BE
   8A		 28	     88	   A0		 08	     A2
   AB		 EF	     88	   3E	       08	     BE
   DA	       28	     88	   02	       08	     A0
   8A	       28	     88	   3E	       0F	     A0

Beginner Exercises

Using the Beginner Exercises in the above Example Program 7-2 as a guide, see if you can change the program to do the following:

1. Change the color of the text to white (color 01) or red (color 10).

2. Write the text to magic address 0000H, then

Change the text back to green in a white background.
Change the text to green in a red background.
Change the text to red in a green background.

3. Shift the character string right 1,2 or 3 pixels.

Version 7.1
Beginner Exercise 3 in EXAMPLE 7-2 was revised
Added comment to EXAMPLE 7-3

End of LESSON 7 document
Custom Expand Write
MCM Design
Jan 2020